home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d1 / formutil.arc / DUMP.DOC < prev    next >
Text File  |  1990-10-26  |  16KB  |  362 lines
  1.    +--------------------------------------------------------------------------+
  2.    |                                                                          |
  3.    |                                  DUMP                                    |
  4.    |                                                                          |
  5.    |                            File Dump Utility                             |
  6.    |                                                                          |
  7.    |                             V3.21 90-10-11                               |
  8.    |                                                                          |
  9.    |                        Author: Peter C. Burrough                         |
  10.    |                                                                          |
  11.    +--------------------------------------------------------------------------+
  12.  
  13.    Program and supporting documentation:
  14.  
  15.        Copyright (c) 1988-1990 by Peter C. Burrough
  16.  
  17.    Function:
  18.  
  19.        Dump any file in hexadecimal, with character equivalents
  20.        for all printable characters
  21.  
  22.    On-line help (operand summary) available by entering:
  23.  
  24.        DUMP   [no operands]
  25.  
  26.    System Requirements:
  27.  
  28.        DOS 2.1 or higher is required.
  29.        ANSI.SYS (or equivalent) must be present.
  30.  
  31.    Distribution:
  32.  
  33.        ZIP file containing executable program and documentation file
  34.        DUMPnnn.ZIP -> DUMPnnn.COM
  35.                       DUMPnnn.DOC
  36.  
  37.        After UNZIPping the file, you may wish to rename DUMPnnn.COM
  38.        to DUMP.COM.
  39.  
  40.    +--------------------------------------------------------------------------+
  41.    |                                                                          |
  42.    |                          Program Invocation                              |
  43.    |                                                                          |
  44.    +--------------------------------------------------------------------------+
  45.  
  46.    Within the following discussion, none of the parameters is case-sensitive.
  47.    Lower case is used to indicate values that are supplied by you; upper case
  48.    is used to signify values that must be coded as shown.
  49.  
  50.    All switches are shown preceded by a "/"; the switch character may be coded
  51.    as "-" for those of you who prefer this character.
  52.  
  53.    The program is invoked as follows:
  54.  
  55.      DUMP filename [range] [/dest] [/hi-bit] [/width] [/base] [/quit] [/K:blks]
  56.  
  57.    where:
  58.  
  59.      "DUMP"     is coded as shown
  60.  
  61.      "filename" is a required parameter, and must be the first parameter
  62.                 specified.  A drive and/or path may be supplied.
  63.  
  64.      "range"    is optional; if omitted, the entire file will be dumped.
  65.                 If specified, then any of the following formats may be used:
  66.  
  67.                   (a) start           [default "stop" value = end of file]
  68.                   (b) start stop
  69.                   (c) Lnnn            [default "start" value = 0]
  70.                   (d) start Lnnn
  71.                   (e) Lnnn start
  72.                   (f) [omitted]       [defaults to entire file]
  73.  
  74.                 "4G-1" below indicates 4,294,967,295 (hex FFFFFFFF)
  75.  
  76.         "start" is the starting offset within the file (range 0 to 4G-1)
  77.                    (default 0)
  78.         "stop"  is the ending offset within the file (range "start" to 4G-1)
  79.                    (default is last byte in file, unless "Lnnn" is coded)
  80.         "L"     is coded as shown, to indicate 'length'
  81.         "nnn"   is the number of bytes to be dumped (range 1 to 4G-1)
  82.                    (default is remaining file length, unless "stop" is coded)
  83.  
  84.                 For format (b), the "stop" value must not be less than the
  85.                 start value.
  86.  
  87.                 For formats (d) and (e), the sum of "start"+"nnn" must not
  88.                 exceed 4G-1.
  89.  
  90.         Radix:  For "start", "stop", and "nnn", the value may be coded with a
  91.                 prefix indicating one of the following bases:
  92.  
  93.              $  (Hexadecimal):     $hhhhhhhh  (max. FFFFFFFF)
  94.              ^  (Decimal    ):   ^nnnnnnnnnn  (max. 4294967295 [4G-1])
  95.              %  (Octal      ):  %kkkkkkkkkkk  (max. 37777777777)
  96.              #  (Binary     ):        #b...b  (max. 1...1 [32 digits])
  97.  
  98.                 If the prefix is omitted, the default base is hexadecimal,
  99.                 unless otherwise overridden by the "/radix" switch (see
  100.                 below).
  101.  
  102.                 In all cases, the print range will be converted to offset
  103.                 values, and shown on the listing in hexadecimal.
  104.  
  105.      "/dest"    is optional; if omitted, the default is "/D"
  106.  
  107.                 This controls the destination of the output, and may be coded:
  108.  
  109.              /D (screen via DOS calls; no color coding)
  110.              /S (screen via BIOS calls, with color coding)
  111.              /M (screen via BIOS calls, monochrome)
  112.              /P (printer direct, via DOS calls)
  113.  
  114.                 If your video adapter card does not support color mode, then /S
  115.                 should be avoided (unpredictable results will occur).
  116.  
  117.                 If you use DOS re-direction to the printer (rather than the /P
  118.                 switch), then you should also avoid /S.
  119.  
  120.                 Refer to the "/width" and "/K:blks" switches below for output
  121.                 sizes.
  122.  
  123.                 Refer to "Color and Character Translation" for color values
  124.                 in use for screen output.
  125.  
  126.      "/hi-bit"  is optional; if omitted, the default is "/7"
  127.  
  128.                 This controls the high-order bit processing for the character
  129.                 portion of the dump for output via DOS calls.  Allowable values
  130.                 are:
  131.  
  132.              /7 (strip the high-order bit)
  133.              /8 (leave the high-order bit as is)
  134.  
  135.                 If /S or /M is in effect, /8 will be assumed unconditionally
  136.                 (/7 will be accepted without any indication of error).
  137.  
  138.                 Refer to "Color and Character Translation" for character
  139.                 translation in the character portion of the output.
  140.  
  141.      "/width"   is optional; if omitted, the default is "/N"
  142.  
  143.                 This controls the page width.  Allowable values are:
  144.  
  145.              /N (narrow) - print 16 bytes of data per line
  146.              /W (wide)   - print 32 bytes of data per line
  147.  
  148.                 For output to the screen, a check will be made to ensure that
  149.                 the current screen width is sufficient to permit /W to be in
  150.                 effect.  If /W output is directed to the printer, it is your
  151.                 responsibility to ensure that the printer has been set up to
  152.                 accept print lines of 132 characters.
  153.  
  154.      "/base"    is optional; if omitted, the default is "/$"
  155.  
  156.                 This controls the radix for "start, "stop" and "nnn" (length)
  157.                 values, unless such values are explicitly coded with a radix
  158.                 indicator.  Allowable values are:
  159.  
  160.              /$ (hexadecimal)
  161.              /^ (decimal)
  162.              /% (octal)
  163.              /# (binary)
  164.  
  165.      "/quit"    is optional; if omitted, the default is "/C"
  166.  
  167.                 This controls the processing of the (Esc) key during program
  168.                 execution.  Allowable values are:
  169.  
  170.              /C (confirmation of Esc key required)
  171.              /Q (quit immediately after Esc key is pressed)
  172.  
  173.      "/K:blks"  is optional; if omitted, the default is "/K:1" for screen
  174.                 output, and "/K:3" for printer output.
  175.  
  176.                 This controls the page length.  The "blks" value must be coded
  177.                 as a one-digit decimal number (range 1 to 9), and defines the
  178.                 number of blocks of data lines per page, where a block consists
  179.                 of 16 print lines, corresponding to 100H bytes in /N mode, and
  180.                 200H bytes of data in /W mode.
  181.  
  182.                 Note that the "/radix" switch has no effect on the
  183.                 interpretation of the number specified for "blks".
  184.  
  185.                 Once the "page" is complete, a new set of header information
  186.                 will be printed (a formfeed will be sent to the printer if /P
  187.                 is in effect).
  188.  
  189.                 If output is directed to the printer, it is your responsibility
  190.                 to ensure that the printer has been set up to accept a minimum
  191.                 of ((16*blks) + 12) lines per page.
  192.  
  193.    Page size:   The default "page" size for output to the screen is 16 lines,
  194.                 plus header information; the default "page" size for output to
  195.                 the printer is 48 lines, plus page header information (with a
  196.                 form-feed sent at the end of every page).
  197.  
  198.    +--------------------------------------------------------------------------+
  199.    |                                                                          |
  200.    |                          Parameter Validation                            |
  201.    |                                                                          |
  202.    +--------------------------------------------------------------------------+
  203.  
  204.    Parameter Parsing Tolerances
  205.    ----------------------------
  206.  
  207.    The "filename" must be present, and must be the first parameter.  However,
  208.    the remaining optional parameters may be coded in any order (with the single
  209.    exception noted below), separated by at least one blank (optionally any
  210.    number of additional blanks will be accepted).
  211.  
  212.    The "/" indicating switch values need not be preceded by a blank.
  213.  
  214.    If the "range" values are codes as 'start stop', then the "stop" value must
  215.    follow the "start" value, although any switch values may occur between the
  216.    two values.
  217.  
  218.    The following are acceptable forms:
  219.  
  220.      DUMP FILE.EXT /P $00F0/8 ^300  range 240 (hex F0)  to 300
  221.      DUMP FILE.EXT L%40 #111        range   7 (bin 111) to  38 (7+32-1)
  222.  
  223.    Parameter errors
  224.    ----------------
  225.  
  226.    Duplicate or conflicting parameters will cause an error to be reported.  For
  227.    example, /D and /S may not appear together; the presence of 3 numeric values
  228.    in the "range" specification is illegal, and so on.
  229.  
  230.    The "start" value may not exceed the file length.
  231.  
  232.    The "stop" value (whether coded explicitly or resulting from "Lnnn") must
  233.    not be less than the "start" value and not greater than the file length.
  234.  
  235.    +--------------------------------------------------------------------------+
  236.    |                                                                          |
  237.    |                       Program Execution Control                          |
  238.    |                                                                          |
  239.    +--------------------------------------------------------------------------+
  240.  
  241.    While the program is executing the following keys will be recognized:
  242.  
  243.    1-9 and 0 (scroll delay rate for screen output)
  244.    -----------------------------------------------
  245.  
  246.      The "1" key will cause a long delay at the end of each line
  247.              (slow scrolling)
  248.      The "9" key will cause a short delay at the end of each line
  249.              (fast scrolling)
  250.      Keys "2" to "8" cause the delay to be progressively decreased
  251.              (i.e. the scroll rate will progressively increase)
  252.      The "0" key will cause a zero delay at the end of each line
  253.              ('express' scrolling)
  254.  
  255.      The program starts at speed "0" ('express')
  256.  
  257.    (spacebar) or "P" key to pause the listing
  258.    ------------------------------------------
  259.  
  260.      After a pause has been requested, any key other than (Esc) will cause the
  261.      dump program to resume.  The (Esc) key will cause the immediate
  262.      termination of the program (regardless of the /C or /Q setting).
  263.  
  264.    (Esc) to request termination
  265.    ----------------------------
  266.  
  267.      After termination has been requested, you will be prompted to confirm the
  268.      request by pressing the (Esc) key a second time if /C is in effect; any
  269.      other key will cause the program to resume.  If /Q is in effect, the
  270.      program will terminate immediately.
  271.  
  272.    Recognition of keystrokes
  273.    -------------------------
  274.  
  275.      Requests for termination or pause will be detected immediately, but will
  276.      not be processed until the end of the current output line.
  277.  
  278.      Similarly, changes in the scroll rate will be detected immediately, but
  279.      will not cause a change in the scroll rate until the end of the current
  280.      output line.
  281.  
  282.    +--------------------------------------------------------------------------+
  283.    |                                                                          |
  284.    |                    Color and Character Translation                       |
  285.    |                                                                          |
  286.    +--------------------------------------------------------------------------+
  287.  
  288.    Color Values
  289.    ------------
  290.  
  291.    For /D, the default DOS color settings will be used.
  292.  
  293.    For /S and /M, the following colors will be used:
  294.  
  295.      character range (hex)      Color for /S     Color for /M
  296.      =======================    =============    =============
  297.      00-1F                      red              white
  298.      20-7F (printable ASCII)    bright yellow    white
  299.      80-9F                      magenta          white
  300.      A0-FF                      bright green     white
  301.  
  302.    Character Translation
  303.    ---------------------
  304.  
  305.    For /S and /M, no character translation will occur (all bytes will be
  306.    displayed as is).
  307.  
  308.    For /D and /P, the following character translation will occur:
  309.  
  310.      character range (hex)     /8            /7
  311.      =======================   ==========    ===========
  312.      00-1F                     . (period)    . (period)
  313.      20-7E (printable ASCII)   as is         as is
  314.      7F                        . (period)    . (period)
  315.      80-9F                     . (period)    . (period)
  316.      A0-FE                     as is         20-7E
  317.      FF                        . (period)    . (period)
  318.  
  319.    +--------------------------------------------------------------------------+
  320.    |                                                                          |
  321.    |                       Program Execution Examples                         |
  322.    |                                                                          |
  323.    +--------------------------------------------------------------------------+
  324.  
  325.    1. DUMP FILE.EXT
  326.  
  327.       Dump the entire file FILE.EXT to the screen
  328.       (note that /D/7 will be assumed)
  329.  
  330.    2. DUMP FILE.EXT/P
  331.  
  332.       Dump the entire file FILE.EXT to the printer
  333.       (note that /7 will be assumed)
  334.  
  335.    3. DUMP FILE.EXT 100 200 /S/8
  336.  
  337.       Dump offset 100H-200H from file FILE.EXT to the screen (with color)
  338.       (no translation will occur for bytes in range 80H-FFH)
  339.  
  340.    4. DUMP FILE.EXT 100 /8
  341.  
  342.       Dump file FILE.EXT to the screen starting at offset 100H, ending at EOF
  343.       (note that /D will be assumed)
  344.  
  345.    5. DUMP FILE.EXT L^50
  346.  
  347.       Dump the first 50 (decimal) bytes of file FILE.EXT to the screen
  348.       (note that /D/7 will be assumed)
  349.  
  350.    6. DUMP FILE.EXT 200 L80
  351.  
  352.       Dump the 80H bytes of file FILE.EXT to the screen, starting at offset 200H
  353.       (note that /D/7 will be assumed)
  354.  
  355.    7. DUMP FILE.EXT $200 L%177
  356.  
  357.       Dump the 127 bytes (octal 177) of file FILE.EXT to the screen, starting at
  358.       offset 512 (hex 200).
  359.       (note that /D/7 will be assumed)
  360.  
  361. *** END OF DOCUMENT ***
  362.